.\" Manual Page for Berkely DB utils, created from upstream
.\" documentation by Thijs Kinkhorst <thijs@kinkhorst.com>.
.TH DB_HOTBACKUP 1 "28 January 2005"
.SH NAME
db_hotbackup \- Create "hot backup" or "hot failover" snapshots
.SH SYNOPSIS
.B db_hotbackup
[-cuVv] [-d data_dir ...] [-h home] [-l log_dir] [-P password] -b backup_dir
.SH DESCRIPTION
The db_hotbackup utility creates "hot backup" or "hot failover" snapshots of Berkeley DB database environments.
.PP
The db_hotbackup utility performs the following steps:
.RS
.IP 1.
If the \-c option is specified, checkpoint the source home database
environment, and remove any unnecessary log files.
.IP 2.
If the target directory for the backup does not exist, it is created with mode
read-write-execute for the owner.
.sp
If the target directory for the backup does exist and the \-u option was
specified, all log files in the target directory are removed; if the \-u option
was not specified, all files in the target directory are removed.
.IP 3.
If the \-u option was not specified, copy application-specific files found in
the database environment home directory, or any directory specified using the
-d option, into the target directory for the backup.
.IP 4.
Copy all log files found in the directory specified by the \-l option (or in the
database environment home directory, if no \-l option was specified), into the
target directory for the backup.
.IP 5.
Perform catastrophic recovery on the hot backup.
.IP 6.
Remove any unnecessary log files from the hot backup. 
.RE
.PP
The db_hotbackup utility does not resolve pending transactions that are in the
prepared state. Applications that use DB_TXN->prepare should specify
DB_RECOVER_FATAL when opening the environment, and run DB_ENV->txn_recover to
resolve any pending transactions, when failing over to the hot backup.
.SH OPTIONS
.IP \fB\-b\fR
Specify the target directory for the backup.
.IP \fB\-c\fR
Before performing the snapshot, checkpoint the source database environment
and remove any log files that are no longer required in that environment.
\fBTo avoid making catastrophic failure impossible, log file removal
must be integrated with log file archival.\fR
.IP \fB\-d\fR
Specify one or more source directories that contain databases; if none
is specified, the database environment home directory will be searched
for database files.  As database files are copied into a single backup
directory, files named the same, stored in different source directories,
could overwrite each other when copied into the backup directory.
.IP \fB\-h\fR
Specify the source directory for the backup, that is, the database
environment home directory.
.IP \fB\-l\fR
Specify a source directory that contains log files; if none is specified,
the database environment home directory will be searched for log files.
.IP \fB\-P\fR
Specify an environment password.  Although Berkeley DB utilities overwrite
password strings as soon as possible, be aware there may be a window of
vulnerability on systems where unprivileged users can see command-line
arguments or where utilities are not able to overwrite the memory
containing the command-line arguments.
.IP \fB\-u\fR
Update a pre-existing hot backup snapshot by copying in new log files.
If the \fB\-u\fR option is specified, no databases will be copied
into the target directory.
.IP \fB\-V\fR
Write the library version number to the standard output, and exit.
.IP \fB\-v\fR
Run in verbose mode, listing operations as they are done.
.PP
The db_hotbackup utility uses a Berkeley DB environment (as described for the
\fB\-h\fR option, the environment variable \fBDB_HOME\fR, or
because the utility was run in a directory containing a Berkeley DB
environment).  In order to avoid environment corruption when using a
Berkeley DB environment, db_hotbackup should always be given the chance to
detach from the environment and exit gracefully.  To cause db_hotbackup
to release all environment resources and exit cleanly, send it an
interrupt signal (SIGINT).
.PP
The db_hotbackup utility exits 0 on success, and >0 if an error occurs.
.SH ENVIRONMENT
.IP \fBDB_HOME\fR
If the \fB-h\fR option is not specified and the environment variable
DB_HOME is set, it is used as the path of the database home, as described
in DB_ENV->open.
.SH AUTHORS
Sleepycat Software, Inc. This manual page was created based on
the HTML documentation for db_hotbackup from Sleepycat,
by Thijs Kinkhorst <thijs@kinkhorst.com>,
for the Debian system (but may be used by others).
